<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Working with UICollectionView  Reference</title>
    <link rel="stylesheet" type="text/css" href="css/jazzy.css" />
    <link rel="stylesheet" type="text/css" href="css/highlight.css" />
    <meta charset='utf-8'>
    <script src="js/jquery.min.js" defer></script>
    <script src="js/jazzy.js" defer></script>
    
    <script src="js/lunr.min.js" defer></script>
    <script src="js/typeahead.jquery.js" defer></script>
    <script src="js/jazzy.search.js" defer></script>
  </head>
  <body>
    <a title="Working with UICollectionView  Reference"></a>
    <header>
      <div class="content-wrapper">
        <p><a href="index.html">IGListKit 4.1.0 Docs</a> (93% documented)</p>
        <p class="header-right"><a href="https://github.com/Instagram/IGListKit"><img src="img/gh.png" alt="GitHub"/>View on GitHub</a></p>
        <div class="header-right">
          <form role="search" action="search.json">
            <input type="text" placeholder="Search documentation" data-typeahead>
          </form>
        </div>
      </div>
    </header>
    <div class="content-wrapper">
      <p id="breadcrumbs">
        <a href="index.html">IGListKit Reference</a>
        <img id="carat" src="img/carat.png" alt=""/>
        Working with UICollectionView  Reference
      </p>
    </div>
    <div class="content-wrapper">
      <nav class="sidebar">
        <ul class="nav-groups">
          <li class="nav-group-name">
            <a href="Guides.html">Guides</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a href="best-practices-and-faq.html">Best Practices and FAQ</a>
              </li>
              <li class="nav-group-task">
                <a href="generating-your-models-using-remodel.html">Generating your models using remodel</a>
              </li>
              <li class="nav-group-task">
                <a href="getting-started.html">Getting Started</a>
              </li>
              <li class="nav-group-task">
                <a href="iglistdiffable-and-equality.html">IGListDiffable and Equality</a>
              </li>
              <li class="nav-group-task">
                <a href="installation.html">Installation</a>
              </li>
              <li class="nav-group-task">
                <a href="migration.html">Migration</a>
              </li>
              <li class="nav-group-task">
                <a href="modeling-and-binding.html">Modeling and Binding</a>
              </li>
              <li class="nav-group-task">
                <a href="vision.html">VISION</a>
              </li>
              <li class="nav-group-task">
                <a href="working-with-core-data.html">Working with Core Data</a>
              </li>
              <li class="nav-group-task">
                <a href="working-with-uicollectionview.html">Working with UICollectionView</a>
              </li>
            </ul>
          </li>
          <li class="nav-group-name">
            <a href="Classes.html">Classes</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a href="Classes/IGListAdapter.html">IGListAdapter</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/IGListAdapterUpdater.html">IGListAdapterUpdater</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/IGListBatchUpdateData.html">IGListBatchUpdateData</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/IGListBindingSectionController.html">IGListBindingSectionController</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/IGListCollectionView.html">IGListCollectionView</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/IGListCollectionViewLayout.html">IGListCollectionViewLayout</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/IGListGenericSectionController.html">IGListGenericSectionController</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/IGListIndexPathResult.html">IGListIndexPathResult</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/IGListIndexSetResult.html">IGListIndexSetResult</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/IGListMoveIndex.html">IGListMoveIndex</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/IGListMoveIndexPath.html">IGListMoveIndexPath</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes.html#/c:objc(cs)IGListReloadDataUpdater">IGListReloadDataUpdater</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/IGListSectionController.html">IGListSectionController</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/IGListSingleSectionController.html">IGListSingleSectionController</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/IGListTransitionData.html">IGListTransitionData</a>
              </li>
            </ul>
          </li>
          <li class="nav-group-name">
            <a href="Constants.html">Constants</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a href="Constants.html#/c:@IGListKitVersionNumber">IGListKitVersionNumber</a>
              </li>
              <li class="nav-group-task">
                <a href="Constants.html#/c:@IGListKitVersionString">IGListKitVersionString</a>
              </li>
            </ul>
          </li>
          <li class="nav-group-name">
            <a href="Enums.html">Enumerations</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a href="Enums/IGListAdapterUpdateType.html">IGListAdapterUpdateType</a>
              </li>
              <li class="nav-group-task">
                <a href="Enums/IGListDiffOption.html">IGListDiffOption</a>
              </li>
              <li class="nav-group-task">
                <a href="Enums/IGListExperiment.html">IGListExperiment</a>
              </li>
            </ul>
          </li>
          <li class="nav-group-name">
            <a href="Protocols.html">Protocols</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a href="Protocols/IGListAdapterDataSource.html">IGListAdapterDataSource</a>
              </li>
              <li class="nav-group-task">
                <a href="Protocols/IGListAdapterDelegate.html">IGListAdapterDelegate</a>
              </li>
              <li class="nav-group-task">
                <a href="Protocols/IGListAdapterMoveDelegate.html">IGListAdapterMoveDelegate</a>
              </li>
              <li class="nav-group-task">
                <a href="Protocols/IGListAdapterPerformanceDelegate.html">IGListAdapterPerformanceDelegate</a>
              </li>
              <li class="nav-group-task">
                <a href="Protocols/IGListAdapterUpdateListener.html">IGListAdapterUpdateListener</a>
              </li>
              <li class="nav-group-task">
                <a href="Protocols/IGListAdapterUpdaterDelegate.html">IGListAdapterUpdaterDelegate</a>
              </li>
              <li class="nav-group-task">
                <a href="Protocols/IGListBatchContext.html">IGListBatchContext</a>
              </li>
              <li class="nav-group-task">
                <a href="Protocols/IGListBindable.html">IGListBindable</a>
              </li>
              <li class="nav-group-task">
                <a href="Protocols/IGListBindingSectionControllerDataSource.html">IGListBindingSectionControllerDataSource</a>
              </li>
              <li class="nav-group-task">
                <a href="Protocols/IGListBindingSectionControllerSelectionDelegate.html">IGListBindingSectionControllerSelectionDelegate</a>
              </li>
              <li class="nav-group-task">
                <a href="Protocols/IGListCollectionContext.html">IGListCollectionContext</a>
              </li>
              <li class="nav-group-task">
                <a href="Protocols/IGListCollectionViewDelegateLayout.html">IGListCollectionViewDelegateLayout</a>
              </li>
              <li class="nav-group-task">
                <a href="Protocols/IGListCollectionViewLayoutCompatible.html">IGListCollectionViewLayoutCompatible</a>
              </li>
              <li class="nav-group-task">
                <a href="Protocols/IGListDiffable.html">IGListDiffable</a>
              </li>
              <li class="nav-group-task">
                <a href="Protocols/IGListDisplayDelegate.html">IGListDisplayDelegate</a>
              </li>
              <li class="nav-group-task">
                <a href="Protocols/IGListScrollDelegate.html">IGListScrollDelegate</a>
              </li>
              <li class="nav-group-task">
                <a href="Protocols/IGListSingleSectionControllerDelegate.html">IGListSingleSectionControllerDelegate</a>
              </li>
              <li class="nav-group-task">
                <a href="Protocols/IGListSupplementaryViewSource.html">IGListSupplementaryViewSource</a>
              </li>
              <li class="nav-group-task">
                <a href="Protocols/IGListTransitionDelegate.html">IGListTransitionDelegate</a>
              </li>
              <li class="nav-group-task">
                <a href="Protocols/IGListUpdatingDelegate.html">IGListUpdatingDelegate</a>
              </li>
              <li class="nav-group-task">
                <a href="Protocols/IGListWorkingRangeDelegate.html">IGListWorkingRangeDelegate</a>
              </li>
            </ul>
          </li>
          <li class="nav-group-name">
            <a href="Type%20Definitions.html">Type Definitions</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a href="Type%20Definitions/IGListCollectionScrollingTraits.html">IGListCollectionScrollingTraits</a>
              </li>
              <li class="nav-group-task">
                <a href="Type%20Definitions.html#/c:IGListUpdatingDelegate.h@T@IGListCollectionViewBlock">IGListCollectionViewBlock</a>
              </li>
              <li class="nav-group-task">
                <a href="Type%20Definitions.html#/c:IGListUpdatingDelegate.h@T@IGListDataSourceChangeBlock">IGListDataSourceChangeBlock</a>
              </li>
              <li class="nav-group-task">
                <a href="Type%20Definitions.html#/c:IGListUpdatingDelegate.h@T@IGListItemUpdateBlock">IGListItemUpdateBlock</a>
              </li>
              <li class="nav-group-task">
                <a href="Type%20Definitions.html#/c:IGListUpdatingDelegate.h@T@IGListObjectTransitionBlock">IGListObjectTransitionBlock</a>
              </li>
              <li class="nav-group-task">
                <a href="Type%20Definitions.html#/c:IGListUpdatingDelegate.h@T@IGListReloadUpdateBlock">IGListReloadUpdateBlock</a>
              </li>
              <li class="nav-group-task">
                <a href="Type%20Definitions.html#/c:IGListSingleSectionController.h@T@IGListSingleSectionCellConfigureBlock">IGListSingleSectionCellConfigureBlock</a>
              </li>
              <li class="nav-group-task">
                <a href="Type%20Definitions.html#/c:IGListSingleSectionController.h@T@IGListSingleSectionCellSizeBlock">IGListSingleSectionCellSizeBlock</a>
              </li>
              <li class="nav-group-task">
                <a href="Type%20Definitions.html#/c:IGListUpdatingDelegate.h@T@IGListToObjectBlock">IGListToObjectBlock</a>
              </li>
              <li class="nav-group-task">
                <a href="Type%20Definitions.html#/c:IGListUpdatingDelegate.h@T@IGListTransitionDataApplyBlock">IGListTransitionDataApplyBlock</a>
              </li>
              <li class="nav-group-task">
                <a href="Type%20Definitions.html#/c:IGListUpdatingDelegate.h@T@IGListTransitionDataBlock">IGListTransitionDataBlock</a>
              </li>
              <li class="nav-group-task">
                <a href="Type%20Definitions.html#/c:IGListAdapter.h@T@IGListUpdaterCompletion">IGListUpdaterCompletion</a>
              </li>
              <li class="nav-group-task">
                <a href="Type%20Definitions.html#/c:IGListUpdatingDelegate.h@T@IGListUpdatingCompletion">IGListUpdatingCompletion</a>
              </li>
            </ul>
          </li>
          <li class="nav-group-name">
            <a href="Functions.html">Functions</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a href="Functions.html#/c:@F@IGListDiff">IGListDiff</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/c:@F@IGListDiffPaths">IGListDiffPaths</a>
              </li>
              <li class="nav-group-task">
                <a href="Functions.html#/c:IGListExperiments.h@F@IGListExperimentEnabled">IGListExperimentEnabled</a>
              </li>
            </ul>
          </li>
          <li class="nav-group-name">
            <a href="Structs.html">Structures</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a href="Structs/IGListCollectionScrollingTraits.html">IGListCollectionScrollingTraits</a>
              </li>
            </ul>
          </li>
        </ul>
      </nav>
      <article class="main-content">
        <section>
          <section class="section">
            
            <h1 id='working-with-code-uicollectionview-code' class='heading'>Working with <code>UICollectionView</code></h1>

<p>This guide provides details on how to work with <a href="https://developer.apple.com/reference/uikit/uicollectionview"><code>UICollectionView</code></a> and <code>IGListKit</code>.</p>
<h2 id='background' class='heading'>Background</h2>

<p>Early versions of <code>IGListKit</code> (2.x and prior) shipped with a subclass of <code>UICollectionView</code> called <a href="https://github.com/Instagram/IGListKit/blob/2.1.0/Source/IGListCollectionView.h"><code><a href="Classes/IGListCollectionView.html">IGListCollectionView</a></code></a>. The class contained <em>no</em> special functionality and was merely used to enforce compile-time restrictions to prevent users from calling certain methods directly on <code>UICollectionView</code>. Beginning with 3.0, <code><a href="Classes/IGListCollectionView.html">IGListCollectionView</a></code> <a href="https://github.com/Instagram/IGListKit/commit/2284ce389708f62d99f48ff2ec15644f1ec59537">was removed</a> for a number of reasons.</p>

<p>For further discussion see <a href="https://github.com/Instagram/IGListKit/issues/240">#240</a> and <a href="https://github.com/Instagram/IGListKit/issues/409">#409</a>.</p>
<h2 id='methods-to-avoid' class='heading'>Methods to avoid</h2>

<p>One of the primary purposes of <code>IGListKit</code> is to perform optimal batch updates for <code>UICollectionView</code>. Thus, clients <strong>should never</strong> call any APIs on <code>UICollectionView</code> that involved reloading, inserting, deleting, or otherwise updating cells and index paths. Instead, use the APIs provided by <a href="https://instagram.github.io/IGListKit/Classes/IGListAdapter.html"><code><a href="Classes/IGListAdapter.html">IGListAdapter</a></code></a>. You should also avoid setting the <a href="https://developer.apple.com/reference/uikit/uicollectionview/1618033-delegate"><code>delegate</code></a> and <a href="https://developer.apple.com/reference/uikit/uicollectionview/1618091-datasource"><code>dataSource</code></a> of the collection view, as this is also the responsibility of <code><a href="Classes/IGListAdapter.html">IGListAdapter</a></code>.</p>

<p>Avoid calling the following methods:</p>
<pre class="highlight objective_c"><code><span class="k">-</span> <span class="p">(</span><span class="kt">void</span><span class="p">)</span><span class="nf">performBatchUpdates</span><span class="p">:(</span><span class="kt">void</span> <span class="p">(</span><span class="o">^</span><span class="p">)(</span><span class="kt">void</span><span class="p">))</span><span class="nv">updates</span>
                 <span class="nf">completion</span><span class="p">:(</span><span class="kt">void</span> <span class="p">(</span><span class="o">^</span><span class="p">)(</span><span class="n">BOOL</span><span class="p">))</span><span class="nv">completion</span><span class="p">;</span>

<span class="k">-</span> <span class="p">(</span><span class="kt">void</span><span class="p">)</span><span class="n">reloadData</span><span class="p">;</span>

<span class="k">-</span> <span class="p">(</span><span class="kt">void</span><span class="p">)</span><span class="nf">reloadSections</span><span class="p">:(</span><span class="n">NSIndexSet</span> <span class="o">*</span><span class="p">)</span><span class="nv">sections</span><span class="p">;</span>

<span class="k">-</span> <span class="p">(</span><span class="kt">void</span><span class="p">)</span><span class="nf">insertSections</span><span class="p">:(</span><span class="n">NSIndexSet</span> <span class="o">*</span><span class="p">)</span><span class="nv">sections</span><span class="p">;</span>

<span class="k">-</span> <span class="p">(</span><span class="kt">void</span><span class="p">)</span><span class="nf">deleteSections</span><span class="p">:(</span><span class="n">NSIndexSet</span> <span class="o">*</span><span class="p">)</span><span class="nv">sections</span><span class="p">;</span>

<span class="k">-</span> <span class="p">(</span><span class="kt">void</span><span class="p">)</span><span class="nf">moveSection</span><span class="p">:(</span><span class="n">NSInteger</span><span class="p">)</span><span class="nv">section</span> <span class="nf">toSection</span><span class="p">:(</span><span class="n">NSInteger</span><span class="p">)</span><span class="nv">newSection</span><span class="p">;</span>

<span class="k">-</span> <span class="p">(</span><span class="kt">void</span><span class="p">)</span><span class="nf">insertItemsAtIndexPaths</span><span class="p">:(</span><span class="n">NSArray</span><span class="o">&lt;</span><span class="n">NSIndexPath</span> <span class="o">*&gt;</span> <span class="o">*</span><span class="p">)</span><span class="nv">indexPaths</span><span class="p">;</span>

<span class="k">-</span> <span class="p">(</span><span class="kt">void</span><span class="p">)</span><span class="nf">reloadItemsAtIndexPaths</span><span class="p">:(</span><span class="n">NSArray</span><span class="o">&lt;</span><span class="n">NSIndexPath</span> <span class="o">*&gt;</span> <span class="o">*</span><span class="p">)</span><span class="nv">indexPaths</span><span class="p">;</span>

<span class="k">-</span> <span class="p">(</span><span class="kt">void</span><span class="p">)</span><span class="nf">deleteItemsAtIndexPaths</span><span class="p">:(</span><span class="n">NSArray</span><span class="o">&lt;</span><span class="n">NSIndexPath</span> <span class="o">*&gt;</span> <span class="o">*</span><span class="p">)</span><span class="nv">indexPaths</span><span class="p">;</span>

<span class="k">-</span> <span class="p">(</span><span class="kt">void</span><span class="p">)</span><span class="nf">moveItemAtIndexPath</span><span class="p">:(</span><span class="n">NSIndexPath</span> <span class="o">*</span><span class="p">)</span><span class="nv">indexPath</span> <span class="nf">toIndexPath</span><span class="p">:(</span><span class="n">NSIndexPath</span> <span class="o">*</span><span class="p">)</span><span class="nv">newIndexPath</span><span class="p">;</span>

<span class="k">-</span> <span class="p">(</span><span class="kt">void</span><span class="p">)</span><span class="nf">setDelegate</span><span class="p">:(</span><span class="n">id</span><span class="o">&lt;</span><span class="n">UICollectionViewDelegate</span><span class="o">&gt;</span><span class="p">)</span><span class="nv">delegate</span><span class="p">;</span>

<span class="k">-</span> <span class="p">(</span><span class="kt">void</span><span class="p">)</span><span class="nf">setDataSource</span><span class="p">:(</span><span class="n">id</span><span class="o">&lt;</span><span class="n">UICollectionViewDataSource</span><span class="o">&gt;</span><span class="p">)</span><span class="nv">dataSource</span><span class="p">;</span>

<span class="k">-</span> <span class="p">(</span><span class="kt">void</span><span class="p">)</span><span class="nf">setBackgroundView</span><span class="p">:(</span><span class="n">UIView</span> <span class="o">*</span><span class="p">)</span><span class="nv">backgroundView</span><span class="p">;</span>
</code></pre>
<h2 id='performance' class='heading'>Performance</h2>

<p>In iOS 10, a new <a href="https://developer.apple.com/reference/uikit/uicollectionviewdatasourceprefetching">cell prefetching API</a> was introduced. At Instagram, enabling this feature substantially degraded scrolling performance. We recommend setting <a href="https://developer.apple.com/reference/uikit/uicollectionview/1771771-isprefetchingenabled"><code>isPrefetchingEnabled</code></a> to <code>NO</code> (<code>false</code> in Swift). Note that the default value is <code>true</code>.</p>

<p>You can set this globally using <code>UIAppearance</code>:</p>
<pre class="highlight objective_c"><code><span class="k">if</span> <span class="p">([[</span><span class="n">UICollectionView</span> <span class="nf">class</span><span class="p">]</span> <span class="nf">instancesRespondToSelector</span><span class="p">:</span><span class="k">@selector</span><span class="p">(</span><span class="nf">setPrefetchingEnabled</span><span class="p">:)])</span> <span class="p">{</span>
    <span class="p">[[</span><span class="n">UICollectionView</span> <span class="nf">appearance</span><span class="p">]</span> <span class="nf">setPrefetchingEnabled</span><span class="p">:</span><span class="nb">NO</span><span class="p">];</span>
<span class="p">}</span>
</code></pre>
<pre class="highlight swift"><code><span class="k">if</span> <span class="kd">#available(iOS 10, *)</span> <span class="p">{</span>
    <span class="kt">UICollectionView</span><span class="o">.</span><span class="nf">appearance</span><span class="p">()</span><span class="o">.</span><span class="n">isPrefetchingEnabled</span> <span class="o">=</span> <span class="kc">false</span>
<span class="p">}</span>
</code></pre>

          </section>
        </section>
        <section id="footer">
          <p>&copy; 2023 <a class="link" href="https://twitter.com/MetaOpenSource" target="_blank" rel="external noopener">Instagram</a>. All rights reserved. (Last updated: 2023-04-07)</p>
          <p>Generated by <a class="link" href="https://github.com/realm/jazzy" target="_blank" rel="external noopener">jazzy ♪♫ v0.14.3</a>, a <a class="link" href="https://realm.io" target="_blank" rel="external noopener">Realm</a> project.</p>
        </section>
      </article>
    </div>
  </body>
</html>
